home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / utils1 / dvtkit13.zip / DVTKIT.DOC < prev    next >
Text File  |  1994-05-16  |  22KB  |  624 lines
  1.  
  2.  
  3.                             The DESQview Toolkit
  4.  
  5.  
  6.                                                         Version 1.3
  7.  
  8.  
  9.         by Gary Chanson
  10.         (C) 1994
  11.  
  12.  
  13.              The DESQview Toolkit is Copyright 1994 by Gary Chanson
  14.              and  Starquest Systems.  No restrictions are placed on
  15.              the non-commercial use of this set of programs.  These
  16.              programs  and  their  documentation  may be copied and
  17.              re-distributed  provided that they are not changed and
  18.              no  fee is charged for  them.  An exception is granted
  19.              to  not-for-profit user's groups, which are authorized
  20.              to  charge a  nominal fee  for materials and handling.
  21.              Starquest Systems and Gary Chanson assume no liability
  22.              for  damages  caused  by  the  use  of these programs.
  23.  
  24.  
  25.          DVToolKIT  is a set of DESQview (tm) specific utilities which give
  26.      command  line  access  to  many  of  the  functions available thru the
  27.      DESQview API.  The set includes:
  28.  
  29.          APPNUM        Returns the window number of the current task.
  30.          DESQ          Pops up the DV main menu and sends a string to it.
  31.          DVM           Sends commands thru the DV window manager.
  32.          FRAME         Turns window frames on or off.
  33.          JUSTIFY       Turns cursor justification on or off.
  34.          KILL          Terminates the specified task.
  35.          MAILBOX       Creates, frees and assigns names to mailboxes.
  36.          MAILBOX.SHP   Shared program which assigns a name to mailbox.
  37.          MESSAGES      Returns the pending message count of a mailbox.
  38.          READMAIL      Reads a message from a mailbox.
  39.          SENDKBD       Sends a string to the keyboard of a task.
  40.          SENDMAIL      Sends a string to the mailbox of a task.
  41.          SOUND         Generates tones from the PC's speaker.
  42.          STATUS        Returns the status of the last mailbox read.
  43.          SWITCH        Script enhancement - switches to or runs a program.
  44.          TITLE         Assigns a title to a window.
  45.          WHOIS         Returns the handle of a task.
  46.          WINDOW        Sets the size and position of a window.
  47.          ZOOM          Zooms the foreground window.
  48.  
  49.      Each of these programs responds to the -? option switch with a
  50.      brief help screen.
  51.  
  52.     =======================================================================
  53.  
  54.     APPNUM
  55.  
  56.         APPNUM  returns  the  window  number  of the current DESQview task.
  57.         This  is also the index number of this task in the DV "Open window"
  58.         menu.  By default, this utility sends its output to STDOUT which is
  59.         normally  the screen.  DOS  output redirection can  be used to send
  60.         its output to a file.  If the -E option is used, the output will be
  61.         stored  in the environment  variable %APPNUM.  If  the -P option is
  62.         used, the window number is added to the PROMPT environment variable
  63.         and  will  be  displayed  as  part  of  the  prompt in this window.
  64.         
  65.  
  66.     Usage:
  67.  
  68.         APPNUM [options]
  69.  
  70.     Options:
  71.  
  72.         -E      returns window number as Environment variable %APPNUM
  73.         -P      add to DOS Prompt
  74.         -Q      Quiet mode
  75.  
  76.     =======================================================================
  77.  
  78.     DESQ
  79.  
  80.         DESQ  pops up the DESQview main menu and sends the specified string
  81.         as  input.  This simulates  the operator pressing  the DESQ key and
  82.         typing  in  the  specified  string.   Embedded commands in the form
  83.         `&<number>' can send any arbitrary key code.  <number> may be any 16
  84.         bit  integer of which the low order  byte is the ASCII code and the
  85.         high  order byte is  the SCAN code.   Numbers prefaced with `$' are
  86.         assumed  to be Hex.  To send a `&' character, replace it with `&&'.
  87.         Note  that actions  initiated on  the menu  will act on the current
  88.         foreground  window.  Execution  from a  background task may produce
  89.         un-expected results.
  90.  
  91.     Usage:
  92.  
  93.         DESQ [options] string
  94.  
  95.     Options:
  96.  
  97.         -C      Close window
  98.         -H      Hex
  99.         -L      pop up Learn menu
  100.         -N      Next window
  101.         -Q      Quiet mode
  102.         &n1     any code
  103.             
  104.     =======================================================================
  105.  
  106.     DVManager
  107.  
  108.         DVManager  translates a series  of window commands  into a DESQview
  109.         window  manager stream  and sends  it to  the default window of the
  110.         specified  task.  If no task is  specified, the stream will be sent
  111.         to the default window of the current task.
  112.  
  113.     Usage:
  114.  
  115.         DVM [options] command command(parameters) ...
  116.  
  117.     Options:
  118.  
  119.         -Tname      destination Task name
  120.         -Thandle    destination Task handle (as returned by WHOIS)
  121.         -Q          Quiet mode
  122.  
  123.     Commands:
  124.  
  125.             ALLOW         EXTEND        PASTE         UP
  126.             ASIDE         FORE          POSITION      VIEWPORT
  127.             BACK          FRAME         REGION        VIRTUAL
  128.             CANCEL        HIDE          RIGHT         WINDOW
  129.             COLOR         LEFT          RUNS          [BOTTOM]
  130.             CURSOR        MAXSIZE       TITLE         [HIDE]
  131.             DISALLOW      MINSIZE       TOP           [TOP]
  132.             DOWN          ORPHAN        UNHIDE        [UNHIDE]
  133.             ECHO
  134.  
  135.  
  136.         ALLOW (list)
  137.             close,hide,suspend,main,switch,open,quit
  138.  
  139.         ASIDE
  140.             suspend task and hides its window
  141.  
  142.         BACK
  143.             force task to background
  144.  
  145.         CANCEL
  146.             cancel operation, remove DV menu, go to topmost process
  147.  
  148.         COLOR (n1)
  149.             set current color
  150.  
  151.         CURSOR (x,y)
  152.             set cursor position.  Upper left corner of window is 0,0
  153.  
  154.         DISALLOW (list)
  155.             close,hide,suspend,main,switch,open,quit
  156.  
  157.         DOWN (x,y,wide,long)
  158.             scroll down the region from x,y to wide,long
  159.  
  160.         ECHO (string)
  161.             display string
  162.  
  163.         EXTEND (yes/no)
  164.             allow window frame to extend beyond screen
  165.  
  166.         FORE
  167.             force task to foreground
  168.  
  169.         FRAME (on/off)
  170.             enable/disable frame around window
  171.  
  172.         HIDE
  173.             hide window
  174.  
  175.         LEFT (x,y,wide,long)
  176.             scroll left the region from x,y to wide,long
  177.  
  178.         MAXSIZE (x,y)
  179.             set maximum size of physical window
  180.  
  181.         MINSIZE (x,y)
  182.             set minimum size of physical window
  183.  
  184.         ORPHAN
  185.             orphan window
  186.  
  187.         POSITION (x,y)
  188.             set position of physical window
  189.  
  190.         REGION (x,y)
  191.             set scrolling region
  192.  
  193.         PASTE
  194.             orphan window and give to system as paste data
  195.  
  196.         RIGHT (x,y,wide,long)
  197.             scroll right the region from x,y to wide,long
  198.  
  199.         RUNS (yes/no)
  200.             enables/disables running in the background
  201.  
  202.         TITLE (name)
  203.             set window title.  This string is displayed in the window
  204.             frame and on the "switch" menu.
  205.  
  206.         TOP
  207.             make window top in system
  208.  
  209.         UNHIDE
  210.             unhide window
  211.  
  212.         UP (x,y,wide,long)
  213.             scroll up the region from x,y to wide,long
  214.  
  215.         VIEWPORT (x,y)
  216.             set position of viewport within window
  217.  
  218.         VIRTUAL (x,y)
  219.             set size of virtual screen
  220.  
  221.         WINDOW (x,y,wide,long)
  222.             set size and position of physical window
  223.  
  224.         [BOTTOM]
  225.             make window bottom in process
  226.  
  227.         [HIDE]
  228.             hide all window of process
  229.  
  230.         [TOP]
  231.             make window top in process
  232.  
  233.         [UNHIDE]
  234.             unhide all window of process
  235.  
  236.  
  237.     ALLOW, DISALLOW commands:
  238.  
  239.         CLOSE               close window
  240.         HIDE                hide window
  241.         MAIN                DV main menu
  242.         OPEN                open window menu
  243.         QUIT                quit DV
  244.         SCISSORS            scissors menu
  245.         SUSPEND             suspend task
  246.         SWITCH              switch windows menu
  247.             
  248.     =======================================================================
  249.  
  250.     FRAME
  251.  
  252.         FRAME  controls the display of a frame around the default window of
  253.         the  specified task.  If no task  is specified, the current task is
  254.         assumed.  A frame can be displayed around a window when the borders
  255.         of  the window are within the  displayable area of the screen.  The
  256.         windows  of  the  current  task  will  have a double border and the
  257.         windows all other tasks will have a single border.
  258.  
  259.     Usage:
  260.  
  261.         FRAME [options] on
  262.         FRAME [options] off
  263.  
  264.     Options:
  265.  
  266.         -Q        Quiet mode
  267.         -Tname    name of Task owning window
  268.         -Thandle  handle of Task owning window (as returned by WHOIS)
  269.  
  270.     =======================================================================
  271.  
  272.     JUSTIFY
  273.  
  274.         JUSTIFY turns window justification on or off for the default window
  275.         of  the current task.   With justification on,  the position of the
  276.         viewport of a window (the portion of the window actually displayed)
  277.         moves  so  that  the  cursor  is  always  within  the window.  With
  278.         justification  off, the position of the viewport remains stationary
  279.         even  if the cursor moves  out of it.  Optional  parameters X and Y
  280.         control  the  position  of  the  viewport  relative  to its window.
  281.  
  282.     Usage:
  283.  
  284.         JUSTIFY off [x,y]
  285.         JUSTIFY on
  286.  
  287.     Options:
  288.  
  289.         -Q      Quiet mode
  290.             
  291.     =======================================================================
  292.  
  293.     KILL
  294.  
  295.         KILL  terminates the specified  task.  The task  name must first be
  296.         assigned to the default mailbox of the task using SPAWN with the -A
  297.         option or MAILBOX.  KILL can be used on any task including the task
  298.         it is called from.
  299.  
  300.     Usage:
  301.  
  302.         KILL [options] task
  303.  
  304.     Options:
  305.  
  306.         -A      Awaken
  307.         -Q      Quiet mode
  308.         -R      Restart
  309.         -S      Suspend
  310.         -T      Terminate
  311.  
  312.     =======================================================================
  313.  
  314.     MAILBOX
  315.  
  316.         MAILBOX  creates,  frees  and  assigns  names  to  mailboxes.   New
  317.         mailboxes  are the property of the  current task, and will be freed
  318.         when  it terminates.  If no task  is specified, the default mailbox
  319.         of  the current  task is  named.  This  identifier is used by other
  320.         utilities  to  obtain  the  handle  of  this  task  for  inter-task
  321.         communications.  Mailboxes can be used to exchange messages between
  322.         tasks  and  as  semaphores  to  control  program  access  and flow.
  323.  
  324.     Usage:
  325.  
  326.         MAILBOX [options] name
  327.  
  328.  
  329.     Options:
  330.  
  331.         -C          Conditional mode (only if un-named) - requires v2.5+
  332.         -E          returns name as Environment variable %MAILBOX - req v2.5+
  333.         -F          Free mailbox
  334.         -N          create New mailbox in current task
  335.         -Q          Quiet mode
  336.         -S          Show name - requires v2.5+
  337.         -Tname      name of mailbox or Task
  338.         -Thandle    handle of mailbox or Task (as returned by WHOIS)
  339.  
  340.     SEMAPHORES:
  341.  
  342.         To  setup a  semaphore, create  a suitably  name mailbox and send a
  343.         message  to it to enable  it.  The first task  to read the mailbox,
  344.         empties  it, executes the program  which needs protection, and then
  345.         sends a new message to the mailbox to re-enable it.  Each task must
  346.         interrogate  the mailbox  using READMAIL  -W.  The  contents of the
  347.         message are not important.
  348.  
  349.         Let's say you want to protect a print job from being disrupted.  To
  350.         start, we need a mailbox named PRINTER as our SEMAPHORE.
  351.  
  352.             MAILBOX -N printer          ; create a mailbox named PRINTER
  353.             SENDMAIL printer free       ; prime it with a message
  354.  
  355.         Now,  all print operations must  check this mailbox before printing
  356.         and re-enable it after.
  357.  
  358.             READMAIL -W -Tprinter       ; test SEMAPHORE and wait...
  359.             PRINT %1 %2 %3              ; safe to print now
  360.             SENDMAIL printer free       ; re-enable SEMAPHORE
  361.  
  362.  
  363.     Error codes returned:
  364.  
  365.         1       Unrecognized option
  366.         2       Illegal parameter
  367.         3       DESQview not available
  368.         4       Task not found
  369.         5       Function not supported by this version of DESQview
  370.         6       No mailbox specified
  371.         7       New mailbox must be in the current task
  372.  
  373.     =======================================================================
  374.  
  375.     MAILBOX.SHP
  376.  
  377.         MAILBOX.SHP   is  a  DESQview  shared  program  which  assigns  the
  378.         specified  data string  as the  name of  the default mailbox of the
  379.         task.   Since  shared  programs  are  called  from  the  DV Program
  380.         Information  File  (.DVP),  no  batch  file  is  needed.  Enter the
  381.         program  path and name  into the "Shared  Program - Pathname" field
  382.         and  the mailbox name into the "Shared Program - Data" field on the
  383.         second page of `Change a Program'.
  384.         
  385.     ┌─────────────────────────────────────────────────────────────────────┐
  386.     │                                Shared Program                       │
  387.     │ Pathname..: C:\DV\MAILBOX.SHP                                       │
  388.     │ Data......: MyName                                                  │
  389.     └─────────────────────────────────────────────────────────────────────┘
  390.  
  391.     =======================================================================
  392.  
  393.     MESSAGES
  394.  
  395.         MESSAGES  returns the status (pending message count) of the mailbox
  396.         of  the specified  task.  If  no task  is specified,  status of the
  397.         default  mailbox of current task will be read.  If the -E option is
  398.         enabled,  status  will  be  returned  as  the  environment variable
  399.         %MESSAGES.  MESSAGES=0 indicates an empty mailbox.
  400.  
  401.     Usage:
  402.  
  403.         MESSAGES [options]
  404.  
  405.     Options:
  406.  
  407.         -E        returns count as Environment variable %MESSAGES
  408.         -Q        Quiet mode
  409.         -Tname    Task to read mailbox status from
  410.         -Thandle  handle of Task to read mailbox status from
  411.  
  412.     =======================================================================
  413.  
  414.     READMAIL
  415.  
  416.         Reads the oldest pending message from the specified mailbox.  If no
  417.         messages  are pending, and the -W  option is enabled, READMAIL will
  418.         wait  for the next  message.  If no  task is specified, the default
  419.         mailbox  of the current task is  read.  Returns the message, status
  420.         and handle of the sender.  If the -E option is enabled, results are
  421.         returned  in environment  variables %MAIL%,  %STATUS% and %SENDER%.
  422.         Status is also returned as ERRORLEVEL.
  423.  
  424.     Usage:
  425.  
  426.         READMAIL [options]
  427.  
  428.     Options:
  429.  
  430.         -E        returns string as Environment variable %MAIL
  431.         -Q        Quiet mode
  432.         -Tname    name of Task (mailbox) to read from
  433.         -Thandle  handle of Task (mailbox) to read from
  434.         -W        Wait if mailbox is empty
  435.  
  436.     =======================================================================
  437.  
  438.     SENDKBD
  439.  
  440.         SENDKBD sends the specified string to the keyboard of the specified
  441.         task.   To the receiving task, the  string will appear to have come
  442.         from  the keyboard, even if the keyboard is not currently available
  443.         to that task.  The string may contain embedded commands in the form
  444.         `&<command>'  which will be expanded and replaced as sent. Embedded
  445.         commands  in the form  `&<number>' can send  any arbitrary KEY CODE.
  446.         <number>  may be any 16 bit integer  of which the low order byte is
  447.         the  ASCII code and the high order  byte is the SCAN code.  Numbers
  448.         prefaced  with `$' are assumed  to be Hex.  To  send `&' replace it
  449.         with `&&'.
  450.  
  451.     Usage:
  452.  
  453.         SENDKBD [options] string
  454.  
  455.     Options:
  456.  
  457.         -H        Hex
  458.         -Q        Quiet mode
  459.         -Tname    destination Task name
  460.         -Thandle  destination Task handle (as returned by WHOIS)
  461.  
  462.     Substitutions:
  463.  
  464.         &BS     BackSpace                   &FF     FormFeed
  465.         &CR     Carriage Return             &LF     LineFeed
  466.         &DEL    DELete                      &NL     New Line
  467.         &EOF    End Of File                 &TAB    TABulation
  468.         &ESC    ESCape                      &BELL   ring BELL
  469.         &Fn1    Function key n1             &n1     any code
  470.             
  471.     =======================================================================
  472.  
  473.     SENDMAIL
  474.  
  475.         SENDMAIL  sends  the  specified  string  to  the specified mailbox.
  476.         Optionally send a status byte with the message.
  477.  
  478.     Usage:
  479.  
  480.         SENDMAIL task string
  481.  
  482.     Options:
  483.  
  484.         -Sn1    set Status
  485.         -Q      Quiet mode
  486.  
  487.     =======================================================================
  488.  
  489.     SOUND
  490.  
  491.         SOUND  generates  tones  from  the  PC's  speaker  at the specified
  492.         frequency  (in Hz) for the specified  duration (in timer ticks).  A
  493.         duration  of  18  ticks  generates  a  tone  of  about 1 second.  A
  494.         frequency  of  0  Hz  generates  silence.   If  both  frequency and
  495.         duration  are zero (or no parameters  are entered), the sound queue
  496.         is cleared.  In note mode, notes can be C, C#, D~, D, D#, E~, E, F,
  497.         F#,  G~,  G,  G#,  A~,  A,  A#,  T (tempo) and R (rest).  One digit
  498.         corresponding  to octave (0  thru 5) must  follow each note without
  499.         any  spaces intervening.  One digit corresponding to tempo (1 thru
  500.         7,   default=5)  must  follow  T.   No  parameter  follows  R.   C2
  501.         corresponds to middle C.  A2 is 440 Hz.
  502.  
  503.     Usage:
  504.  
  505.         SOUND [options] freq,ticks freq,ticks freq,ticks ...
  506.         SOUND [options] T6 C2 A#3 R B1 ...
  507.  
  508.     Options:
  509.  
  510.         -Q      Quiet mode
  511.             
  512.     =======================================================================
  513.  
  514.     SWITCH
  515.  
  516.         SWITCH  takes the name of a mailbox from the keyboard or script and
  517.         switches  to the window containing that program if already running.
  518.         If  not, the specified DVP file is  spawned using the Open Menu key
  519.         following the semi-colon or the first two characters of the mailbox
  520.         name  unless  a  DVP  file  is  specified  as  part of the command.
  521.  
  522.     Usage:
  523.  
  524.         SWITCH [mailbox-name] [dvp-file]
  525.  
  526.     Usage in DESQview scripts:
  527.  
  528.           {DESQ}oSW<name>{Enter}
  529.       or  {DESQ}oSW<name>;<key>{Enter}
  530.  
  531.     =======================================================================
  532.  
  533.     TITLE
  534.  
  535.         TITLE  assigns  the  specified  string  as  the window title of the
  536.         specified  task.   If  no  task  is  specified, the current task is
  537.         assumed.  This is the string which is displayed in the frame of the
  538.         window  and on the  "Open window" menu.   It should not be confused
  539.         with  the  name  assigned  to  the  mailbox.   Its  use  is totally
  540.         cosmetic.
  541.  
  542.     Usage:
  543.  
  544.         TITLE [options] string
  545.  
  546.     Options:
  547.  
  548.         -Q        Quiet mode
  549.         -Tname    name of Task
  550.         -Thandle  handle of Task (as returned by WHOIS)
  551.  
  552.     =======================================================================
  553.  
  554.     WHOIS
  555.  
  556.         WHOIS  returns the handle of the specified task.  Its purpose is to
  557.         test  for the existence of a  task with the specified mailbox name.
  558.         It can be used to prevent a program from being run in more than one
  559.         window.
  560.  
  561.     usage:
  562.  
  563.         WHOIS [options] task
  564.  
  565.     options:
  566.  
  567.         -E        returns handle as Environment variable %TASK
  568.         -E:name   returns handle as Environment variable %NAME
  569.         -Q        Quiet mode
  570.  
  571.     =======================================================================
  572.  
  573.     WINDOW
  574.  
  575.         WINDOW  sets the  size and  position of  the default  window of the
  576.         specified  task.   If  no  task  is  specified, the current task is
  577.         assumed.
  578.  
  579.     usage:
  580.  
  581.         WINDOW [options] col,row,wide,long
  582.  
  583.     options:
  584.  
  585.         -Q        Quiet mode
  586.         -Tname    name of Task owning window
  587.         -Thandle  handle of Task owning window (as returned by WHOIS)
  588.  
  589.     =======================================================================
  590.  
  591.     ZOOM
  592.  
  593.         ZOOM  switches the default window of  the current task between full
  594.         screen mode and windowed mode.
  595.  
  596.     Usage:
  597.  
  598.         ZOOM
  599.  
  600.     =======================================================================
  601.  
  602.  
  603.  
  604.      ┌───────────────────────────────────────────────────────────────────┐
  605.      │                                                                   │
  606.      │        Special thanks to Ralf Brown and his Interrupt List        │
  607.      │         which helped make this set of utilities possible.         │
  608.      │                                                                   │
  609.      └───────────────────────────────────────────────────────────────────┘
  610.  
  611.  
  612.  
  613.             Please forward all comments and bug reports to:
  614.  
  615.                 Gary Chanson
  616.  
  617.                 31 Chester Avenue
  618.                 Waltham, MA  02154
  619.  
  620.                 617-899-4771 - voice
  621.                 617-899-6672 - Archane Incantations BBS
  622.  
  623.                 Email:  Gary.Chanson@Channel1.com
  624.